/*
 * Copyright (c) 2007-2008, Sun Microsystems, Inc.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in
 *       the documentation and/or other materials provided with the
 *       distribution.
 *     * Neither the name of Sun Microsystems, Inc. nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.sun.sgs.io;

import java.io.IOException;

/**
 * Represents a connection for data communication, independent of the QoS
 * properties of the connection's transport or protocol. An associated
 * {@link ConnectionListener} is notified of asynchronous events on the
 * connection.
 */
public interface Connection {

   /**
    * Asynchronously sends data on this connection.
    * <p>
    * The specified byte array must not be modified after invoking this method;
    * if the byte array is modified, then this method may have unpredictable
    * results.
    * 
    * @param message
    *           the message data to send
    * 
    * @throws IOException
    *            if there was a synchronous problem sending the message
    */
   void sendBytes(byte[] message) throws IOException;

   /**
    * Asynchronously closes this connection, freeing any resources in use. The
    * connection should not be considered closed until
    * {@link ConnectionListener#disconnected disconnected} is invoked on the
    * {@linkplain ConnectionListener listener}.
    * 
    * @throws IOException
    *            if there was a synchronous problem closing the connection
    */
   void close() throws IOException;

}
